/*----------------------------------------------------------------------*
 *	INTERFACE:	Qt3Game
 *	Quantum Tic Tac Toe
 *	Copyright (c) 2004-2009 Novatia Labs, Inc.  All rights reserved.
 *----------------------------------------------------------------------*/

package com.novatialabs.qttt.engine;

/**
 * Qt3Game defines the interface to a game of Quantum Tic Tac Toe.
 *
 * @Author	Duane Gibson
 * @Author Friendly development resources cheerfully provided by Charles Phares.
 * @Author	$Author$
 * @Version	$Revision$
 */

public interface Qt3Game
{

   /* ----------------------------------------------------------------- *
    * Methods for determining the current state of the game.
    * ----------------------------------------------------------------- */

    /** Returns whether the game is over. */
    public abstract boolean isGameOver();

   /**
    * Returns the winner of the game.
    * If "X" won, returns the constant 'Qt3Player.X'.
    * If "O" won, returns the constant 'Qt3Player.O'.
    * If the game is a "Cat's Game", returns null.
    * @throws IllegalStateException if the game is not over.
    */
    public abstract Qt3Player getWinner()
	throws IllegalStateException;

    public static enum Score {
	NO_POINTS,
	HALF_POINT,
	FULL_POINT,
	POINT_AND_A_HALF,
	DOUBLE_POINTS;
    }

   /**
    * Returns the score of the winner.
    * @throws IllegalStateException if the game is not over.
    */
    public abstract Score getWinnerScore()
	throws IllegalStateException;

   /**
    * Returns the score of the loser.
    * @throws IllegalStateException if the game is not over.
    */
    public abstract Score getLoserScore()
	throws IllegalStateException;

   /**
    * Returns the number (1-9) of the next move.
    * @throws IllegalStateException if all moves have been played (and
    *		the game is over).
    */
    public abstract int getMoveNumber();

   /**
    * Returns the player who should make the next move.
    * @throws IllegalStateException if all moves have been played (and
    *		the game is over).
    */
    public abstract Qt3Player getPlayerToMove();

    /** Returns whether the next step is a resolution. */
    public abstract boolean isResolutionNeeded();

    /** Returns a description of the squares in the quantum board. */
    public abstract Qt3Square[] getBoardSquares();

   /**
    * Returns the set of classical Tic Tac Toe games currently represented
    * by the state of the Quantum Tic Tac Toe game.
    */
    public abstract Qt3ClassicalBoard[] getClassicalEnsemble();

   /**
    * Returns the standard notation for all the moves of the game.
    */
    public abstract String[] getNotationForMoves();

   /**
    * Returns the classical notation for all the moves of the game.
    */
    public abstract String[] getClassicalNotationForMoves();

   /* ----------------------------------------------------------------- *
    * Methods for making moves.
    * ----------------------------------------------------------------- */

   /**
    * Places the next move of the game in the indicated squares.
    *
    * @param	square1		number of the first square in which to move.
    * @param	square2		number of the second square in which to move.
    * @return whether this move ends the game.
    * @throws	IllegalArgumentException if either square is an invalid square
    *			number (less than one or greater than nine).
    * @throws	Qt3InvalidMoveException	if the arguments do not identify
    *			 a valid move.
    * @throws	IllegalStateException if a move is not the next step in the
    *			 game or the game is over.
    */
    public abstract boolean placeMove(
	int	square1,	// number of the first square (1-9)
	int	square2		// number of the second square (1-9)
	)
	throws	IllegalArgumentException,
		Qt3InvalidMoveException,
		IllegalStateException;

   /**
    * Resolves an entanglement created by the current move.
    *
    * @param	square		The square chosen for the resolution.
    * @param	move		The move that was chosen to exist in the square.
    * @return whether this resolution ends the game.
    * @throws	IllegalArgumentException if the square is an invalid square
    *			number (less than one or greater than nine) or the
    *			move does not identify a valid move number.
    * @throws	Qt3InvalidMoveException	if the arguments do not resolve the
    *			current entanglement.
    * @throws	IllegalStateException if a resolution is not the next step
    *			in the game or the game is over.
    */
    public abstract boolean resolveSquareToMove(
	int	square,
	int	move
	)
	throws	IllegalArgumentException,
		Qt3InvalidMoveException,
		IllegalStateException;

   /* ----------------------------------------------------------------- *
    * Methods for editing the state of the game.
    * ----------------------------------------------------------------- */

   /**
    * Resets the game state to that of a new, initial game.
    */
    public abstract void newGame();

   /**
    * Changes the state of the game back to the state before the previous
    * move or entanglement-resolution.  The un-done moves are remembered and
    * can be re-applied with redoMove().
    *
    * @throws	IllegalStateException if there are no moves to undo.
    */
    public abstract void undoMove();

   /**
    * Re-applies a move that was previously un-done with undoMove() or
    * resetMoves().
    *
    * @return whether this move ends the game.
    * @throws	IllegalStateException if there are no moves to re-apply.
    */
    public abstract boolean redoMove();

   /**
    * Performs an undoMove() on all previous moves in the game.
    * The moves can be re-applied with redoMove().
    */
    public abstract void resetMoves();

   /* ----------------------------------------------------------------- *
    * Methods for getting and setting game engine properties.
    * ----------------------------------------------------------------- */

   /**
    * Returns whether moves will be normalized (to have the lowest square
    * index first).
    */
    public abstract boolean isNormalizingMoveSquares();

   /* ----------------------------------------------------------------- *
    * Methods for getting general info.
    * ----------------------------------------------------------------- */

   /**
    * Returns a version string identifying the version of this
    * implementation of Quantum Tic Tac Toe.
    */
    public abstract String getVersionString();

} // interface Qt3Game

